home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / CHIP Kasım 1998.iso / emulators / gameboy / vgbdos88dos.exe / VGB.TXT < prev   
Text File  |  1997-07-02  |  24KB  |  544 lines
  1.                       ******* Virtual GameBoy *******
  2.                    The Portable Nintendo GameBoy Emulator
  3.                              Ms-Dos version 0.88
  4.                              Linux version 0.79
  5.  
  6.         Core emulator code copyright (C) 1995,1996 Marat Fayzullin
  7.         MS-DOS port copyright        (C) 1996 Marcel de Kogel
  8.         SVGA-lib code copyright      (C) 1995 Thierry Lescot
  9.         Additional Features          (C) 1997 Hans de Goede
  10.  
  11.                                      
  12.                GameBoy is a registered trademark of Nintendo.
  13.                  MS-DOS is a trademark of Microsoft Corp.
  14.  
  15.  
  16. Introduction
  17. ============
  18.  
  19. Please, *carefully* read this manual. Do not write me email with
  20. questions answered in here, as such letters are going to be ignored: I
  21. have too many other things to do to answer the same questions over and
  22. over again.
  23.  
  24. Virtual GameBoy (VGB) is a portable emulator of the Nintendo GameBoy
  25. handheld videogame console written in C. Although many things do not work
  26. quite well yet, it was able to run about 85% of games checked with it. 
  27.  
  28. GameBoy-related archives with technical and other info are located at:
  29.  
  30.                   http://www.freeflight.com/fms/GameBoy/
  31.                   ftp://ftp.komkon.org/pub/GameBoy/
  32.  
  33. There are versions of VGB for Amiga, Macintosh, and IBM PC (both MeSsyDOS
  34. and Windoze). Following people are maintaining ports of VGB to these
  35. systems:
  36.  
  37. Linux Svgalib, Enhanced X and MSDOS:
  38. Hans de Goede [j.w.r.degoede@et.tudelft.nl]
  39. http://www.et.tudelft.nl/~jdegoede/
  40.  
  41. Windows and Unix/X
  42. Marat Fayzullin [fms@wam.umd.edu]
  43. http://www.freeflight.com/fms/
  44.  
  45. Macintosh:
  46. John Stiles [jstiles@cello.gina.calstate.edu]
  47.  
  48. This document covers the following versions:
  49. Ms-Dos
  50. Linux Svgalib
  51. Linux X enhanced
  52.  
  53.  
  54. Hardware Requirements
  55. =====================
  56. A 486DX-33 (486DX2-66 recommended)
  57. A VGA compatible video card
  58. Adlib/Adlib Gold/SBPro/SB16 and joystick supported
  59.  
  60.  
  61. Software requirements:
  62. ======================
  63.  
  64. Ms-Dos:
  65. -------
  66.  
  67. VGB-DOS requires the presence of a DPMI server. If you don't run the
  68. program under a DPMI-hosted environment (Windows, OS/2, QPMI, ...), put
  69. the file CSDPMI.EXE included in CWSDPMI.ZIP somewhere in your path.
  70.  
  71. Linux-Svgalib:
  72. --------------
  73.  
  74. The Linux Svgalib version requires svgalib, this version must run as root!
  75. The joystick module and the oss-lite sound drivers are also supported.
  76.  
  77. Unix/x:
  78. -------
  79.  
  80. Requires an 8-bit depth x-server preferable with MIT-SHM extensions
  81. The linux/x version again supports the joystick module and OSS drivers.
  82. If you want sound run this one as root!, otherwise use "vgbx -sound 0"
  83.  
  84.  
  85. Files included in VGB-DOS.ZIP
  86. ==============================
  87. VGB-DOS.EXE    The emulator
  88. VGB-DBG.EXE    The emulator with intergrated debugger.
  89. VGB.TXT        This file
  90. VGB.GIF        A GIF file containing the title screen. You can replace
  91.                this with your own. Make sure the file is in 256-color,
  92.                320x200, non-interlaced GIF87A format. The first 64 colors
  93.                are reserved for use by the emulator
  94. KEYS.EXE       Small utility to alter the key mappings
  95. CONVERT.EXE    Small utility to convert old .cfg files to the new format
  96. CWSDMI.ZIP     A DPMI server required by VGB-DOS.EXE
  97.  
  98.  
  99. Files included in vgb-linux.zip
  100. ===============================
  101. vgb            The svgalib executable make this sui root!
  102. xvgb           The X executable if you want to use sound also make this one
  103.                sui root! Otherwise run with -sound 0.
  104. xvgb-dbg       X executable with debugger.
  105. vgb.txt        This file
  106. vgb.gif        A GIF file containing the title screen. You can replace
  107.                this with your own. Make sure the file is in 256-color,
  108.                320x200, non-interlaced GIF87A format. The first 64 colors
  109.                are reserved for use by the emulator
  110. joy-patch.dif  A patch to the linux joystick module 0.8.0 to allow use of
  111.                4 button joysticks.
  112.                Aplly with "patch < joypatch.dif" in the directory where you 
  113.                unpacked the joystick module source. 
  114.                (the dir containing the joystick-0.8.0 dir that is)
  115.                And recompile your joystick module as instructed in the docs.
  116.  
  117. Default Key Mappings
  118. ====================
  119. Cursor Keys  -  Movement
  120. Left Alt     -  Button A
  121. Left Ctrl    -  Button B
  122. Left Shift   -  Start
  123. Z            -  Select
  124.  
  125.  
  126. Special Keys
  127. ============
  128. q,w,e,r      -  Toggle sound channels 1-4 on/off (dos version only)
  129. t            -  Toggle sound on/off              (dos version only)
  130. y            -  Save current settings to <cart-name>.cfg 
  131. o            -  Pause & Blank screen (toggle)    (dos version only)
  132. p            -  Pause (toggle)
  133. grey -       -  Decrease volume.
  134. grey +       -  Increase volume
  135. ESC          -  Quit emulator
  136. F1 - F4      -  Select Backgroundcolor 0 - 3
  137. F5 - F8      -  Select Spritecolor 0 - 3
  138. F9 - F12     -  Select Windowcolor 0 - 3
  139. 1            -  Increase red for selected color
  140. 2            -  Decrease red for selected color
  141. 3            -  Increase green for selected color
  142. 4            -  Decrease green for selected color
  143. 5            -  Increase blue for selected color
  144. 6            -  Decrease blue for selected color
  145.  
  146. Special Keys in the debugger version only
  147. =========================================
  148. A            -  Enter the debugger
  149. S            -  Display sprite information
  150. D            -  Display lcd state registers
  151.  
  152.  
  153. Command line options
  154. ====================
  155. All commandline options are excepted by all versions covered by this doc.
  156. But when it says (version x only) this means they only do something in
  157. that version). This is to keep the .cfg files compatible along different
  158. versions.
  159.  
  160. -help                          Print a help page describing all available
  161.                                command line options
  162. -ifreq <frequency>             Select interrupt frequency [60]
  163.                                If you want your games to run faster,
  164.                                increase the interrupt frequency. If you
  165.                                want them to run slower, decrease it.
  166. -verbose <level>               Select debugging messages [1]
  167.                                0 - Silent           1 - Startup messages
  168.                                2 - Illegal writes   4 - Illegal CPU ops
  169.                                8 - Bank switching
  170. -vperiod <period>              Set VBlank interrupts period [69905 cycles]
  171. -uperiod <period>              Number of interrupts per screen update [-1]
  172.                                Selecting -1 will enable real-time refresh
  173.                                checking.If the emulation is chunky, try:
  174.                                -uperiod 2 or -uperiod 3
  175. -autosave                      Save currents settings to <cart-name>.cfg
  176.                                on exit.
  177. -cheat <GG code>               Activate GameGenie cheat [none]
  178. -delay/-nodelay                Delay/Don't delay screen refresh [-delay]
  179. -crc/-nocrc                    Check/Don't check cartridge CRC [-crc]
  180. -video <mode>                  Select video mode [0] (not available in X)
  181.                                0 - 320x200 with title screen
  182.                                1 - 320x200 without title screen
  183.                                2 - 360x144 full screen mode
  184.                                3 - 180x144 full screen mode
  185.                                4 - 256x200 with title screen
  186.                                5 - 256x200 without title screen
  187.                                Please note that modes 2-5 may not be
  188.                                compatible with your VGA card or monitor
  189. -background <filename>         Select GIF file to use as background(Not under X)
  190.                                [vgb.gif] (Only works in video modes 0 and 4)
  191. -joystick <mode>               Select joystick mode
  192.                                0 - disabled
  193.                                1 - autodetected
  194. -sound <mode>                  Select sound mode [1]
  195.                                0 - No sound
  196.                                1 - Adlib
  197.                                You may want to have the sound turned off
  198.                                by default for certain games, as the
  199.                                emulation isn't nearly perfect
  200. -stereo <mode>                 Select stereo mode [1]
  201.                                0 - mono
  202.                                1 - normal
  203.                                2 - reversed
  204. -volume <value>                Select initial volume [10]. 0 is silent, 15
  205.                                is maximum. In dos volume control only works on
  206.                                SBPro or SB16 compatible cards
  207. -bcolorX      <color>          Changes the background/sprite/window colors.
  208. -spritecolorX <color>          The <color> argument should be:
  209. -windowcolorX <color>          "#rrggbb", where r=red, b=blue an g =green.
  210.                                these are hex values!, colornames are no
  211.                                longer supported!
  212. -swapbuttons <flags>           Select buttons to swap [0] (msdos only)
  213.                                1 - Swap joystick fire-buttons
  214.                                2 - Swap keyboard fire-buttons
  215.                                3 - Swap both fire-buttons
  216.                                4 - Remap buttons for gravis gamepad
  217. -autoa <mode>                  Select button A autofire mode [0] 0 - No
  218.                                autofire 1 - Autofire
  219. -autob <mode>                  Select button B autofire mode [0] 0 - No
  220.                                autofire 1 - Autofire
  221. -keys <string>                 Alter key mappings (see note!)
  222.  
  223. Note on -keys:
  224. ==============
  225.  
  226. The string taken by -keys looks something like:
  227. "1122334455667788"
  228. where the numbers are hex-representation of the scancodes for:
  229. 1 : left
  230. 2 : right
  231. 3 : up
  232. 4 : down
  233. 5 : button a
  234. 6 : button b
  235. 7 : start
  236. 8 : select
  237.  
  238. Due to the way the keyboard routines work this is the only option which is a
  239. bit different for the different versions so put it in vgb-<version>.cfg .
  240. - For starters the x-windows  version ignores option (still to come ?)
  241. - The svgalib version doesn't support extended keycodes but maps the grey
  242.   cursor keys to the old numeric keypad.
  243. So the string for the default-keymapping are:
  244. Dos:     "CBCDC8D0381D2A2C" ,this completly maches with the scan codes.
  245. Svgalib: "4B4D4850381D2A2C" ,note how the cursor keys have changed, because
  246. we now use the scancodes for the numeric keypad, cause ext-keys are not 
  247. supported. But due to the remapping of svgalib the grey cursor keys also work.
  248.  
  249.  
  250. Configuration files
  251. ===================
  252. The emulator loads two configuration files (if present) before it loads a
  253. cartridge rom:
  254.  
  255. "vgb-dos.cfg" or "vgb-unix.cfg" located in the CURRENT! directory.
  256. There is a seperate cfg for each version for some platform dependend options.
  257. (see the note above on -keys).
  258.  
  259. cart.cfg (e.g. "dkong.cfg" if you load "dkong.gb") located in the cartridge
  260. dump's directory.
  261.  
  262. These are plain text files containing optional commandline options.
  263. Options can be separated with spaces, tabs or returns.
  264.  
  265.  
  266. Troubleshooting
  267. ===============
  268. -  If the emulator refuses to load your ROM images, check if it's CRC is
  269.    correct and if it's size is a multiple of 8192 bytes. If it's CRC is
  270.    incorrect, you might want to try using -nocrc, although getting a
  271.    correct image is prefered. If it's size is incorrect, there might be a
  272.    SmartCard header attached to the file. Try stripping the first 512
  273.    bytes
  274. -  If a game doesn't run correctly, try increasing vperiod to about 100000
  275. -  If display is incorrect, try -delay or -uperiod 0
  276.  
  277. Note I'm starting a list of specific options needed to run certain games,
  278. please mail me any games you know need a specificoption to run.
  279.  
  280. Game:                     Needed Option:
  281.  
  282. Mario Land 2              -vperiod 75000
  283.  
  284.  
  285.  
  286. Version specific Comments:
  287. ==========================
  288.  
  289. Ms-Dos:
  290. -------
  291.  
  292. There has changed a lot with this version, not visually but under the hood.
  293. Since I'm now also working on a linux version there has been a complete
  294. source tree merge between the Ms-dos and unix version. I now can specify
  295. which version I want to compile with one define in the makefile.
  296.  
  297. This also means almost every commandline option has changed. (see above)
  298. For one the colorscheme support has disappeared! The same is possible with
  299. the -XcolorX options and the colorscheme code was a big mess. Also colornames 
  300. are nolonger supported!
  301.  
  302. I realise this is a bit inconvienient but this really needed to be done to
  303. get a clean code base at which some serious coding could (and has) been done.
  304. I've added a convert utility to the dos-distribution just run "convert *.cfg"
  305. to convert all your old cfg files to the new commandline options.
  306. Colorschemes and names will be converted to the -XcolorX option.
  307. So if you liked a specific colorscheme just make a vgb-dos.cfg file and
  308. run convert on it. I hope this eases the pain ,I just really needed to get
  309. things cleaned up including all those worthless commandline options.
  310.  
  311. Version 0.88 is the latest dos-version, all the bugs I know of have been fixed.
  312. And keeping vgb-dos in sync with the linux version would mean breaking my 
  313. agreement with Marat that I would only do bugfixes, since from now on a 
  314. lott of new features will be introduced.
  315.  
  316. From now on the DOS-port is officially discontinued as requested by Marat.
  317.  
  318.  
  319. Linux generic comments:
  320. -----------------------
  321.  
  322. If you want to play with joystick you need to have a loaded joystick module,
  323. you can always get the latest joystick module from:
  324.  
  325. ftp://sunsite.unc.edu/pub/Linux/kernel/patches/console
  326. (At the time of writing the latest version is: 0.8.0)
  327.  
  328. If you want to use a 4 button joystick you will need a slightly modified
  329. joystick module, just apply the patch and recompile*. This should be
  330. 100% backwards compatible. I'm working on getting this into the official
  331. joystick-module.
  332.  
  333. * = Aplly with "patch < joypatch.dif" in the directory where you 
  334.     unpacked the joystick module source. 
  335.     (the dir containing the joystick-0.8.0 dir that is)
  336.     And then recompile your joystick module as instructed in the docs.
  337.  
  338. The linux version from now on uses the emulation core of vgb-dos mainly
  339. because the vgb-dos core is 20 - 30% faster ! this shouldn't hurt
  340. compatibility, but please notify me if any games stop working!
  341.  
  342. The sound routines don't use the OSS-drivers. Instead they directly write to
  343. the opl registers. This is done cause the gb-sound hardware looks a lot 
  344. like an adlib and otherwise it would be one hell of a job to emulate. This 
  345. means vgb needs root! rights to get permission to directly write to the opl.
  346. Also don't run any other sound(midi) programs when running vgb. Your pc
  347. shouldn't crash on this but the sound it makes will be horrible.
  348. Although vgb doesn't use the OSS-lite drivers for the sound it still needs 
  349. them. For one it needs them to detect wether there is an opl3. 
  350. Oss-lite is also used for the mixer functions.
  351.  
  352. Note: if you don't have an opl it won't be detected, so you don't have 
  353. to run xvgb as root. Vgb-svgalib still needs root for the svgalib.
  354.  
  355.  
  356. Linux svgalib:
  357. --------------
  358. First of all a very big thanks to Ulrich Hecht. He originally came with the 
  359. idea to use Thierry Lescot's svga-lib code for vgb-linux. He also beat me to 
  360. releasing a svgalib-version of vgb. Since that day we've been sharing sources.
  361. I've done my own adaptation of Thierry's sources to the newest vgb.
  362. I've done this mainly because I wanted a clean version whit cross-platform
  363. compability. I did however use Ulrich's code for the joystick support.
  364.  
  365. Thanks for all the help Ulrich. 
  366.  
  367. I've given my vgb-linux version no 0.76 to clearly indicate that it superceeds
  368. Ulrich's version it does the same, plus somethings extra.
  369.  
  370.  
  371. History
  372. =======
  373.  
  374. Although al versions originaly came from marat. They've quite grown apart.
  375. So there's a different old-history for each version. From this release on all 
  376. versions who are maintained by me will stay in sync, so they've a combined 
  377. history. Version numbers will probably get matched in the future 
  378.  
  379. Current combined release:
  380. -------------------------
  381. Dos   0.88 -DOS: This is the latest DOS-release as requested by Marat,
  382. Linux 0.79  The dos version now is officially discontinued.
  383.             My work on the linux version will continue however.
  384.            -Fixed bug in the opl2 routines, now opl2's are detected and used 
  385.             succesfully again.
  386.            -Fixed a bug which only saved the first 8kb of battery-backed-ram
  387.             even if there was more, Thanks go to Mogu for reporting this.
  388.  
  389. Dos   0.87 -Changed the default -uperiod from 0 to -1, -1 now is realtime 
  390. Linux 0.78  refresh-checking. This was done so that a frameskip of 0 could
  391.             be manually forced.
  392.            -Thanks to Paul Robson author of gb97 Donkey Kong 97 is fixed.
  393.             If you're a dos user be sure to check out his great gb-emu at:
  394.             http://members.aol.com/~autismuk/gameboy.htm
  395.            -Added -swapbuttons 4 for gravis gamepad owners.
  396.            -Linux: added realtime-refreshchecking.
  397.            -Linux: framecount is corrected for pause.
  398.            -Linux: sound is turned of when vgb isn't active.
  399.            -Linux: added background gif support to svgalib version.
  400.            -Linux: -swapbuttons is implemented
  401.            -Linux: -support for 4 button joysticks, see linux notes
  402.            -Linux: vgb doesn't dump core anymore when it can't get the 
  403.             io-permissions for the sound-output instead it issues a warning
  404.             and continues with sound disabled.
  405.  
  406. Dos   0.86 -Switched from the unix emulation core to marcel's dos-core
  407. Linux 0.77  Basicly both core's are the same but although marat's code is 
  408.             cleaner, marcel's is much faster. This means the dos-version is 
  409.             back up to speed. The linux version now is 20 - 30% faster!
  410.             Thanks to the guy who told me how slow the new vgb-dos was.
  411.            -I've also optimised the drawing routines a bit which also should
  412.             speed things up a bit.
  413.            -Fixed a bug which made the emulator crash when a cartridge file
  414.             without extension was given on the commandline. 
  415.            -Dos: fixed the realtime syncing routine's. Realtime sync now is
  416.             disabled when specifying a uperiod other as 0.
  417.  
  418. Dos   0.85 -First combined release based one big merged source tree. 
  419. Linux 0.76  This means lotts of changes especially for the dos-version
  420.             So read this doc, even if you've read it for an old version.
  421.            - -joystick added to en/disable joystick. 
  422.            -Svga-lib version added, with colorchanging and option saving. 
  423.            -Dos:  -nodelay made default following the unix version.
  424.            -Dos:  keyboard handling cleaned up vgb should once again run under
  425.                   windows 311.
  426.            -Unix: sound and joystick support added. 
  427.            -Unix: serial io interrupt emulated, taken from the dos-version.  
  428.            -Unix: changed keys to follow the dos-keys:
  429.                   cursor-keys     :movement
  430.                   shift-key       :start
  431.                   z-key           :select 
  432.                   left-alt        :fire A
  433.                   left-crtl       :fire B
  434.  
  435. Prior Dos versions:
  436. -------------------
  437.  
  438. 0.84  - Added -autosave to the -help commandline parameter list
  439.       - When saving options the gif-file used for the background is also saved
  440.       - Fixed a nasty bug in the string parsing of the options-saving-routine,
  441.         Strange enough this bug only showed at the compaq prolinea's we have at
  442.         school.
  443. 0.83  - Last updated release, since Marat wants the dos-port discontinued,
  444.         check Marat's vgb page for more info, coming soon.
  445.         Maybe one more release to fix bugs, but no more update's.
  446.         Still, if you find any port specific bugs, please mail.
  447.         Please don't mail any this game won't run bugs. 
  448.         Only port specific bugs , your soundcard not being recognised,
  449.         for example.
  450.       - Source-code no longer available on request of Marat
  451.       - Options and colors can now be saved by pressing Y
  452.       - -autosave added to save options on exit
  453.       - vgb-dbg.exe added to the distribution. This is vgb-dos with an 
  454.         integrated debugger, a tat slower though. Debugger information is now
  455.         displayed readable and entering the debugger doen't crash the emu
  456.         anymore.
  457. 0.82    I (Hans) took over the msdos-port since Marcel has dropped it,
  458.     on the fly color-changing for easy creation of color-schemes.  
  459.         Quite Some keys changed do to the new color-scheme-changing.
  460. 0.8b1   Fixed LCD state and serial I/O emulation, implemented sprite
  461.         priorities and improved sprite refreshing, added autofire options,
  462.         soundtrack can now be saved into a file, key mappings can now be
  463.         changed, increased speed
  464. 0.6.2   Fixed a major bug in the GB's timer interrupt scheme and a minor
  465.         bug in the RAM page allocation scheme
  466. 0.6.1   Fixed lots of bugs, added sprite color control
  467. 0.5.2   Major speedup, added sync option, fixed some bugs, added color
  468.         scheme support and a few other options
  469. 0.5.1   Initial release
  470.  
  471.  
  472. Prior Unix-versions:
  473. --------------------
  474.  
  475. Ulrich's vgb-linux releases:
  476. 0.7.5 - bugfix: SB volume control works now
  477.       - autodetection of ports and joystick presence implemented
  478.       - on-the-fly joystick calibration implemented
  479. 0.7.4 - fixed a bug that made it impossible to disable the Sound Blaster
  480. 0.7.3 - first public release
  481.  
  482. Marat's original releases:
  483. 0.7 - CPU emulation is somewhat sped up
  484.     - CPU cycles (not ops) are now used for synchronization
  485.     - LCD controller's state changes are done correctly
  486.       (which may slow things down somewhat)
  487.     - Sprite priorities implemented
  488.       (which may slow things down somewhat)
  489.     - RAM size bug fixed
  490.     - Separate autofire for buttons A and B
  491.     - Saving soundtrack into a file
  492.     - Separate colors for background, window, and sprites
  493.     - -nodelay is made default now
  494.  
  495.  
  496. Whats Next
  497. ==========
  498.  
  499. Dos:
  500. ----
  501.  
  502. Nothing, as asked by Marat. I just released this last few versions as a total 
  503. clean-up so if there are any bugs yo fix or nice features to add I can do it 
  504. easily. So keep the bug reports flowing, I'll still do bug-fixes.
  505. But please do not send any reports about not working games instead try the 
  506. trouble shooting options. And mail me if you find a way to make a game work.
  507.  
  508. Unix/Linux generic:
  509. -------------------
  510.  
  511. I'm working on gb link emulation for the unix version of vgb.
  512. I don't know wether I'll succeed. All info on the gb link and related stuff
  513. is appreciated.
  514.  
  515. X-windows:
  516. ----------
  517.  
  518. - Add support for 16, 24 and 32 bpp servers.
  519. - Add color changing and palette saving.
  520. - Add window scaling
  521.  
  522. Credits
  523. =======
  524.  
  525. - The real work for this emu was done by Marcel and Marat. 
  526.   Thanks for all the hard work Marcel and Marat.
  527. - Thanks to Thierry Lescot for the original svga-lib code
  528. - Thanks to Ulrich Hecht for his work on the svga-lib code and the joystick 
  529.   support for linux.
  530. - Thanks to Paul Robson author of gb97 for the donkey Kong fix and all the  
  531.   future help. 
  532.   If you're a dos user be sure to check out his great gb-emu at:
  533.   http://members.aol.com/~autismuk/gameboy.htm
  534. - VGB-DOS was compiled using DJ Delorie's DJGPP v2.01 DJGPP is a 32 bit C
  535.   compiler for MS-DOS. Source code and binaries of DJGPP are available at
  536.   http://www.delorie.com.
  537.  
  538. Please send your comments to me (Hans) at j.w.r.degoede@et.tudelft.nl
  539.  
  540. -BUT PLEASE, do NOT ask for ROM IMAGES!,
  541. nor NAG about some games not working,
  542. instead try the trouble shooting hints,
  543. they work with most games.
  544.